home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / rpcgen_tli.z / rpcgen_tli
Text File  |  1998-10-20  |  18KB  |  265 lines
  1.  
  2.  
  3.  
  4. rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))                                                    rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii - an RPC protocol compiler
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _i_n_f_i_l_e
  13.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _[[[[_----_DDDD_n_a_m_e_[[[[_====_v_a_l_u_e_]]]]_]]]] _[[[[_----_TTTT_]]]] _[[[[_----_IIII _|||| _----_KKKK _s_e_c_s_]]]] _i_n_f_i_l_e
  14.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_cccc_||||_----_hhhh_||||_----_llll_||||_----_mmmm_||||_----_tttt _[[[[_----_oooo _o_u_t_f_i_l_e _]]]] _i_n_f_i_l_e
  15.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_ssss _n_e_t_t_y_p_e _[[[[_----_oooo _o_u_t_f_i_l_e_]]]] _i_n_f_i_l_e
  16.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_nnnn _n_e_t_i_d _[[[[_----_oooo _o_u_t_f_i_l_e_]]]] _i_n_f_i_l_e
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii is a tool that generates C code to implement an RPC protocol.
  20.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii will produce files to be used with libnsl [see _iiii_nnnn_tttt_rrrr_oooo_...._3333_nnnn(1)].
  21.      To produce files to be used with the libc see _rrrr_pppp_cccc_gggg_eeee_nnnn(1).  The input to
  22.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii is a language similar to C known as RPC Language (Remote
  23.      Procedure Call Language).
  24.  
  25.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii is normally used as in the first synopsis where it takes an
  26.      input file and generates up to four output files.  If the _i_n_f_i_l_e is named
  27.      _pppp_rrrr_oooo_tttt_oooo_...._xxxx, then _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii will generate a header file in _pppp_rrrr_oooo_tttt_oooo_...._hhhh, XDR
  28.      routines in _pppp_rrrr_oooo_tttt_oooo______xxxx_dddd_rrrr_...._cccc, server-side stubs in _pppp_rrrr_oooo_tttt_oooo______ssss_vvvv_cccc_...._cccc, and client-
  29.      side stubs in _pppp_rrrr_oooo_tttt_oooo______cccc_llll_nnnn_tttt_...._cccc.  With the _----_TTTT option, it will also generate
  30.      the RPC dispatch table in _pppp_rrrr_oooo_tttt_oooo______tttt_bbbb_llll_...._iiii.
  31.  
  32.      The server created can be started both by the port monitors (for example,
  33.      _iiii_nnnn_eeee_tttt_dddd or _llll_iiii_ssss_tttt_eeee_nnnn) or by itself.  When it is started by a port monitor, it
  34.      creates servers only for the transport for which the file descriptor _0000
  35.      was passed.  The name of the transport must be specified by setting up
  36.      the environment variable _PPPP_MMMM______TTTT_RRRR_AAAA_NNNN_SSSS_PPPP_OOOO_RRRR_TTTT.  When the server generated by
  37.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii is executed, it creates server handles for all the transports
  38.      specified in _NNNN_EEEE_TTTT_PPPP_AAAA_TTTT_HHHH environment variable, or if it is not set, it
  39.      creates server handles for all the visible transports from _////_eeee_tttt_cccc_////_nnnn_eeee_tttt_cccc_oooo_nnnn_ffff_iiii_gggg
  40.      file.  Note:  the transports are chosen at run time and not at compile
  41.      time.  When the server is self-started, it backgrounds itself by default.
  42.      A special symbol, _RRRR_PPPP_CCCC______SSSS_VVVV_CCCC______FFFF_GGGG, can be defined at compilation time to make
  43.      the server process run in foreground.
  44.  
  45.      The second synopsis provides special features which allow for the
  46.      creation of more sophisticated RPC servers.  These features include
  47.      support for user provided _####_dddd_eeee_ffff_iiii_nnnn_eeee_ssss and RPC dispatch tables.  The entries
  48.      in the RPC dispatch table contain:
  49.           +o  pointers to the service routine corresponding to that procedure,
  50.           +o  a pointer to the input and output arguments
  51.           +o  the size of these routines
  52.      A server can use the dispatch table to check authorization and then to
  53.      execute the service routine; a client library may use it to deal with the
  54.      details of storage management and XDR data conversion.
  55.  
  56.      The other three synopses shown above are used when one does not want to
  57.      generate all the output files, but only a particular one.  Some examples
  58.      of their usage is described in the EXAMPLE section below.  When
  59.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii is executed with the _----_ssss option, it creates servers for that
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))                                                    rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))
  71.  
  72.  
  73.  
  74.      particular class of transports.  When executed with the _----_nnnn option, it
  75.      creates a server for the transport specified by _n_e_t_i_d.  If _i_n_f_i_l_e is not
  76.      specified, _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii accepts the standard input.
  77.  
  78.      The C preprocessor, _cccc_cccc _----_EEEE [see _cccc_cccc(1)], is run on the input file before it
  79.      is actually interpreted by _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii.  For each type of output file,
  80.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii defines a special preprocessor symbol for use by the
  81.      _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii programmer:
  82.  
  83.      _RRRR_PPPP_CCCC______HHHH_DDDD_RRRR     defined when compiling into header files
  84.      _RRRR_PPPP_CCCC______XXXX_DDDD_RRRR     defined when compiling into XDR routines
  85.      _RRRR_PPPP_CCCC______SSSS_VVVV_CCCC     defined when compiling into server-side stubs
  86.      _RRRR_PPPP_CCCC______CCCC_LLLL_NNNN_TTTT    defined when compiling into client-side stubs
  87.      _RRRR_PPPP_CCCC______TTTT_BBBB_LLLL     defined when compiling into RPC dispatch tables
  88.  
  89.      Any line beginning with `_%%%%' is passed directly into the output file,
  90.      uninterpreted by _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii.
  91.  
  92.      For every data type referred to in _i_n_f_i_l_e, _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii assumes that there
  93.      exists a routine with the string _xxxx_dddd_rrrr_____ prepended to the name of the data
  94.      type.  If this routine does not exist in the RPC/XDR library, it must be
  95.      provided.  Providing an undefined data type allows customization of XDR
  96.      routines.
  97.  
  98.      The following options are available:
  99.  
  100.      _----_cccc   Compile into XDR routines.
  101.  
  102.      _----_DDDD_n_a_m_e_[[[[_====_v_a_l_u_e_]]]]
  103.           Define a symbol _n_a_m_e.  Equivalent to the _####_dddd_eeee_ffff_iiii_nnnn_eeee directive in the
  104.           source.  If no _v_a_l_u_e is given, _v_a_l_u_e is defined as _1111.  This option
  105.           may be specified more than once.
  106.  
  107.      _----_hhhh   Compile into _CCCC data-definitions (a header file).  _----_TTTT option can be
  108.           used in conjunction to produce a header file which supports RPC
  109.           dispatch tables.
  110.  
  111.      _----_IIII   Compile support for _iiii_nnnn_eeee_tttt_dddd(1M) in the server side stubs.  Such
  112.           servers can be self-started or can be started by _iiii_nnnn_eeee_tttt_dddd.  When the
  113.           server is self-started, it backgrounds itself by default.  A special
  114.           define symbol _RRRR_PPPP_CCCC______SSSS_VVVV_CCCC______FFFF_GGGG can be used to run the server process in
  115.           foreground, or the user may simply compile without the _----_IIII option.
  116.  
  117.           If there are no pending client requests, the _iiii_nnnn_eeee_tttt_dddd servers exit
  118.           after 120 seconds (default).  The default can be changed with the _----_KKKK
  119.           option.  All the error messages for _iiii_nnnn_eeee_tttt_dddd servers are always logged
  120.           with _ssss_yyyy_ssss_llll_oooo_gggg(3).
  121.  
  122.           Note:  this option is supported for backward compatibility only.  By
  123.           default, _rrrr_pppp_cccc_gggg_eeee_nnnn generates servers that can be invoked through
  124.           portmonitors.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))                                                    rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))
  137.  
  138.  
  139.  
  140.      _----_KKKK _s_e_c_s
  141.           By default, services created using _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii wait _1111_2222_0000 seconds after
  142.           servicing a request before exiting.  That interval can be changed
  143.           using the _----_KKKK flag.  To create a server that exits immediately upon
  144.           servicing a request, _----_KKKK _0000 can be used.  To create a server that
  145.           never exits, the appropriate argument is _----_KKKK _----_1111.
  146.  
  147.           When monitoring for a server, some portmonitors, like _llll_iiii_ssss_tttt_eeee_nnnn(1M),
  148.           _a_l_w_a_y_s spawn a new process in response to a service request.  If it
  149.           is known that a server will be used with such a monitor, the server
  150.           should exit immediately on completion.  For such servers, _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii
  151.           should be used with _----_KKKK _----_1111.
  152.  
  153.      _----_llll   Compile into client-side stubs.
  154.  
  155.      _----_mmmm   Compile into server-side stubs, but do not generate a main routine.
  156.           This option is useful for doing callback-routines and for users who
  157.           need to write their own main routine to do initialization.
  158.  
  159.      _----_nnnn _n_e_t_i_d
  160.           Compile into server-side stubs for the transport specified by _n_e_t_i_d.
  161.           There should be an entry for _n_e_t_i_d in the netconfig database.  This
  162.           option may be specified more than once, so as to compile a server
  163.           that serves multiple transports.
  164.  
  165.      _----_oooo _o_u_t_f_i_l_e
  166.           Specify the name of the output file.  If none is specified, standard
  167.           output is used (_----_cccc, _----_hhhh, _----_llll, _----_mmmm, _----_nnnn, _----_ssss and _----_tttt modes only).
  168.  
  169.      _----_ssss _n_e_t_t_y_p_e
  170.           Compile into server-side stubs for all the transports belonging to
  171.           the class _n_e_t_t_y_p_e.  The supported classes are _nnnn_eeee_tttt_pppp_aaaa_tttt_hhhh, _vvvv_iiii_ssss_iiii_bbbb_llll_eeee,
  172.           _cccc_iiii_rrrr_cccc_uuuu_iiii_tttt______nnnn, _cccc_iiii_rrrr_cccc_uuuu_iiii_tttt______vvvv, _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______nnnn, _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______vvvv, _tttt_cccc_pppp, and _uuuu_dddd_pppp [see
  173.           _rrrr_pppp_cccc(3N) for the meanings associated with these classes].  This
  174.           option may be specified more than once.  Note:  the transports are
  175.           chosen at run time and not at compile time.
  176.  
  177.      _----_tttt   Compile into RPC dispatch table.
  178.  
  179.      _----_TTTT   Generate the code to support RPC dispatch tables.
  180.  
  181.      The options _----_cccc, _----_hhhh, _----_llll, _----_mmmm, _----_ssss and _----_tttt are used exclusively to generate a
  182.      particular type of file, while the options _----_DDDD and _----_TTTT are global and can
  183.      be used with the other options.
  184.  
  185. NNNNOOOOTTTTEEEESSSS
  186.      The RPC Language does not support nesting of structures.  As a work-
  187.      around, structures can be declared at the top-level, and their name used
  188.      inside other structures in order to achieve the same effect.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))                                                    rrrrppppccccggggeeeennnn____ttttlllliiii((((1111))))
  203.  
  204.  
  205.  
  206.      Name clashes can occur when using program definitions, since the apparent
  207.      scoping does not really apply.  Most of these can be avoided by giving
  208.      unique names for programs, versions, procedures and types.
  209.  
  210.      The server code generated with _----_nnnn option refers to the transport
  211.      indicated by _n_e_t_i_d and hence is very site specific.
  212.  
  213. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  214.      The following example:
  215.  
  216.           _$$$$ _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_TTTT _pppp_rrrr_oooo_tttt_...._xxxx
  217.  
  218.      generates all the five files:  _pppp_rrrr_oooo_tttt_...._hhhh, _pppp_rrrr_oooo_tttt______cccc_llll_nnnn_tttt_...._cccc, _pppp_rrrr_oooo_tttt______ssss_vvvv_cccc_...._cccc,
  219.      _pppp_rrrr_oooo_tttt______xxxx_dddd_rrrr_...._cccc and _pppp_rrrr_oooo_tttt______tttt_bbbb_llll_...._iiii.
  220.  
  221.      The following example sends the C data-definitions (header file) to the
  222.      standard output.
  223.  
  224.           _$$$$ _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_hhhh _pppp_rrrr_oooo_tttt_...._xxxx
  225.  
  226.      To send the test version of the _----_DDDD_TTTT_EEEE_SSSS_TTTT, server side stubs for all the
  227.      transport belonging to the class _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______nnnn to standard output, use:
  228.  
  229.           _$$$$ _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_ssss _dddd_aaaa_tttt_aaaa_gggg_rrrr_aaaa_mmmm______nnnn _----_DDDD_TTTT_EEEE_SSSS_TTTT _pppp_rrrr_oooo_tttt_...._xxxx
  230.  
  231.      To create the server side stubs for the transport indicated by _n_e_t_i_d _tttt_cccc_pppp,
  232.      use:
  233.  
  234.           _$$$$ _rrrr_pppp_cccc_gggg_eeee_nnnn______tttt_llll_iiii _----_nnnn _tttt_cccc_pppp _----_oooo _pppp_rrrr_oooo_tttt______ssss_vvvv_cccc_...._cccc _pppp_rrrr_oooo_tttt_...._xxxx
  235.  
  236. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  237.      _cccc_cccc(1), _rrrr_pppp_cccc_gggg_eeee_nnnn(1)
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.